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Introducing the BREW 
Sample Applications 


The Binary Runtime Environment for Wireless? (BREWº) Software Development Kit (BREW 
SDKº) includes several sample applications created with BREW that demonstrate the use of 
many interfaces and controls commontly used in BREW application development. The sample 
applications can be found in the <BREWisdkiexamples> directory. The purpose of these 
samples is to identify the BREW APIs and controls that allow each application to accomplish 
its intended task and describe the functionality of each of the BREW applications from the 
user's perspective. 


NOTE: The sample source code provided with the BREW SDK has been written to 
demonstrate the usage of BREW data structures and functions. Despite the extensive testing 
that each sample application undergoes, the source code was not intended to pass the 
requirements of TRUE BREWº Testing because the sample applications are not fully featured. 


The following BREW sample applications are included: 


Expense Tracker Describes a simple expense tracking application that allows 
the device user to record new expenses (by paymenttype) as 
they are accrued. Expenses can be saved in files that can be 
loaded and viewed when needed. 


MediaPlayer Describes a multimedia application capable of playing sound 
and video clips, including audio clips that you recorded using 
the application. You can also display still graphic images. 
Standard controls, such as play, fast forward, rewind, stop, 
pause, and record, are demonstrated. 


NeiDiagnostics Describes an application that allows the device user to 
perform echo tests using Transmission Control Protocol 
Internet Protocol (TCP/IP), User Datagram Protocol Internet 
Protocols (UDP/IP), and Hypertext Transfer Protocol (HTTP). 


Road Warrior Describes an application that accesses a web server and 
delivers real-time traffic data for major San Diego highways. 
The web server URL and highways are configurable. 
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WhiteBoard Describes a “virtual whiteboard” application that allows the 
user to draw geometric shapes of various sizes and colors. 
The size of shapes is limited by the device screen size, and 
the choice of colors is limited by the device's supported color 
depth. 


NOTE: The <BREWisdkiexamples> directory also includes the HelloWorld sample 
application. 


BREW documentation 


This guide is part of an information set that includes the following documents: 


BREW SDK User Docs Describes the SDK and how to use its components. 

BREW Programming Concepis Provides key BREW programming principles. 

BREW AP!| Reference Provides a reference for all BREW APIs. 

Creating a BREW Application Provides a tutorial designed to guide new BREW application 
from Scratch developers through the creation of their first BREW 


application. It also provides an overview of the components of 
the BREW SDK as they relate to application development. 


Requesting new BREW features 


Do you have ideas for features that would make the BREW SDK more valuable and useful to 
you? If so, send us email at brew-request(Oqualcomm.com. Each request is evaluated, and a 
member of the New Features Response Team will respond to your email. 


For more information 


Online information and support is available for BREW application developers. Please visit the 
BREW web site for details: www.qualcomm.com/brew/. 
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Expense Tracker is a travel expense-tracking application that allows the device user to record 
expenses for a defined period of time. The user can track the date of the transaction, payment 
types, and purchase amount, and enter a description of the expense. Expenses can be 
reviewed, either for the entire period or on a transaction-by-transaction basis. When all 
expenses have been entered in the database, the user can generate a text file report that can 
be viewed onscreen. 


Expense Tracker specifications 


The following table lists the interfaces and controls used in the development of Expense 
Tracker, along with the files you need to run the application on the handset. 


Interfaces used Controls used Files needed on handset 
IDatabase IDateCil expensetracker.bar 
IDBMgr IDialog expensetracker.mií 
IDBRecord IStatic expensetracker.mod 

IFile ITextCtl expensetracker.sig 
IFileMgr help.txt 


Running Expense Tracker on the handset 


Before exploring the underlying code that makes Expense Tracker work, let's take a look at 
the application from the user's perspective; that is, how it works on a handset. 
To run Expense Tracker 


1. Run the BREW Simulator and make sure the MIF Directory setting is pointing to 
<BREWisdkiexamples>. 


2. Choose the Expense Tracker application. 
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BREW loads the Expense Tracker applet—that is, the Expense Tracker applet 
dynamic-link library (DLL)—and starts the application. A splash screen opens, and 
a screen similar to the following appears: 


Tull 
EExpenseTracker 


Main Menu 
Cd dd New 
CI view 


E= Options 
? Help 
o About 





3. From the Expense Tracker Main Menu, you can perform the following functions: 


Select this option To do this 


Add New Enter a new expense record into the database. See Adding new 
expenses on page 8 for instructions. 


View View and, if needed, edit existing expense records for the 
current time period. See Viewing expenses on page 9 or Editing 
expense records on page 11 for instructions. 


Options Load and view an existing expense report and save the current 
expenses in the database into a flat file for viewing. See Saving 
and loading expense reporis on page 12 for instructions. 


Help View online instructions for using Expense Tracker. 


About View copyright and version information for Expense Tracker. 


4. To return to the previous screen, press CLR. 


5. Tostop the applet at any time, press End. 


Adding new expenses 


The Add New menu option lets you record expense information on a transaction-by- 
transaction basis. That is, each expense transaction is a separate record in the database. For 


each expense, you store the date that the transaction occurred, the type of payment used, the 
amount, and a brief description. 
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To add a new expense 


1. 


Choose Add New from the Expense Tracker Main Menu. 


The Add New screen opens. 





- The Date defaults to today's date. If you need to change it, highlight the value you 


wantto change, then press the up or down arrow keys to increase or decrease the 
value. 


NOTE: To advance to the next field, press the right arrow key. 


For Type, press the up or down arrow keys to scroll through the paymenttypes until 
the correct one is displayed. The available types are Cash, Credit, Check, and 
Debit. 


For Amount, use the number keys to enter a value, then press the right arrow key 
to accept the amount. As you enter the amount, the values are backfilled to the left. 
For example, to enter an amount of $200.35, you would enter 20035. To enter an 
amount of 50 cenis, you would enter 50. 


For Desc, enter up to 16 characters to describe the expense. 
When you are finished, press Select. 
To add the expense, press Done. 


The Expense Tracker Main Menu reopens. 


Viewing expenses 


The View option on the Expense Tracker Main Menu allows you to view expenses recorded 
for a specified date range. You can view all transactions of a particular payment type or for all 


types. 
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NOTE: The expense records remain in the database until you save them to a flat file report. 
At that time, the database is cleared for the date range. 

To view expenses 

1. Choose View from the Expense Tracker Main Menu. 


The View Parameters screen opens. 


Tull «EO 


e ExpenseTracker 
View Parameters 


Type: áll 
From: Map 20, 2002 


To: Hay 20, 2002 





2. For Type, select a payment type (All, Cash, Credit, Check, and Debit) for the 
expense. If you select a type other than All, only expenses of that type will be 
viewable. 


3. In From and To, enter the range of dates for which you want to view expenses of 
the selected type. 


4. When the correct parameters are shown, press View. 


The Expenses screen opens, showing the expenses for the specified range of 
dates, along with a total at the bottom. 


Tull 
EEspenseTracker 


Too 





Total: 444,4] 
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5. From this screen, you can do the following: 


* To see the description of each expense, press the up or down arrow keys. 
* To return to the View screen, press the CLR key. 


* Toeditan expense, highlight it and press Select. See Editing expense records 
below. 


Editing expense records 


After you have added and viewed expenses, you can edit them, as needed, until you have 
saved them into a report. 


To edit an expense 


1. View the expenses you want to edit, as described in the previous procedure. 


Tull (UNE) 
EEspenseTracker 


TA 


Total: 444,4] 





2. Highlight the expense you want to edit and press Select. 


The Edit Expense screen opens. 


Tall MO! 
Edit Expense 

Date: [BM eU, «OD 
Type: Debit 

Amount $ 1505 


Desc: Starbucks 


1 Done Erase 





3. Edit the information in the same way that you added it. 
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4. When you have finished editing the expense record, press Select and do one of 


the following: 


- Press Erase to delete the record. 


* Press Done to save the changes. 


The Expenses screen reopens and the changes are reflected in the total. 


Saving and loading expense reports 


When you have finished entering expenses for a particular time period—at the end of a 
business trip, for example—you can save the expenses into a flat file report for later viewing. 
After you have saved the report, the individual expense records are deleted to save space on 
your device. Saved reports can be loaded at any time to view the expense information. 


To load an existing expense report 


1. 





Choose Options from the Expense Tracker Main Menu. 


The Options menu screen opens. 


all € UHE] 
EF ExpenseTracker 
Options 


pi Load Report 
bd Save Report 


NOTE: If you haven't added any expense records since the last time you saved a 
report, the Save Report option will not be shown in the menu. 
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2. Choose Load Report. 


The Load Report screen opens. 


Tull € Doo] 
EExpenseTracker 
Load Report 

20 Ma 2002 - 20 MAY 





3. Highlight the report you want to load and press Select. 


The Expense Report screen opens. 


Tull Mo 
EFExpenseTracker 


Repor 
Di 2002 


20 Mar Une 
Starbucks 
Debi, £15.05 





4. When you are finished viewing the report, press Select. 
The Expense Report screen closes and the Expense Tracker Main Menu screen 
reopens. 

To save expenses into an expense report 

1. Choose Options from the Expense Tracker Main Menu. 


The Options menu screen opens. 
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Tull 
EFExpenseTracker 
Options 


Do Load Report 
E Save Feport 





2. Choose Save Report. 


The Save Report verification screen opens. 


Tall MO 
EExpenseTracker 
Save Repoll 

This wall remove all 
entres from the 
database. ÁIe VOL SUE 


ou giant to save” 





3. To save the report and delete the expense records, press Yes. 


The report is saved, the individual expense records are deleted, and the Options 
menu screen reopens. 


What Expense Tracker demonstrates 


Expense Tracker demonstrates how to create a BREW application that utilizes file handling 
and database capabilities, as well as various GUI controls provided in the BREW SDK. The 
Expense Tracker interface uses several menus that allow the user to access various program 
capabilities, including adding new expenses to the expense database, performing database 
queries, editing and erasing expenses, and generating expense reporis for onscreen viewing. 


Users enter, search, edit, and erase expense records using a set of forms that allow 
information to be entered on the phone screen. These forms demonstrate a variety of BREW 
controls, including IMenuCtl, IDateCil, ITextCtl, IStatic, and a custom control called 
CAmountCil that was designed specifically for this application. Forms are implemented 
programmatically using the IDialog interface which uses form controls created with the BREW 
Resource Editor. 
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Expense Tracker also demonstrates implementation of a BREW database application that 
uses the IDatabase, IDBMgr, and IDBRecord interfaces, as well as IFileMgr and IFile for file 


handling. The sample application supporis localization using the BREW Resource Editor to 
define string and image values used by the application. 
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MediaPlayer is a multimedia application capable of playing sound and video clips, and 
displaying still graphic images. The application can also record and play back QUALCOMM 
PureVoice (QCP) audio clips if you have the appropriate CMX DLLs loaded. Up to 32 
multimedia files can be stored for use with this application. MediaPlayer includes standard 
controls, such as play, fast forward, rewind, stop, pause, and record. MediaPlayer supporis a 
wide variety of audio, video, and still graphic formats including QCP, MPEG Audio Layer 3 
(MP3), Musical Instrument Digital Interface (MIDI), BREW Compressed Image (BCl|), Bitmap 
(BMP), and Packet Mode Data (PMD), which contains both audio and video. 


MediaPlayer specifications 


The following table lists the interfaces and controls used in the development of MediaPlayer, 
along with the files you need to run the application on the handset. 


Interfaces used Controls used Files needed on handset 
IMedia IDisplay mediaplayer.bar 
File mediaplayer.mif 


mediaplayer.mod 


EM mediaplayer.sig 
IMenuCil 
IStatic You also need to include media 


files in a directory called “media” on 
the handset. 


Running MediaPlayer on the handset 


Before exploring the underlying code that makes MediaPlayer work, take a look at the 
application from the user's perspective; that is, how it works on a handset. 
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To run MediaPlayer 


1. Run the BREW Simulator and make sure the MIF Directory setting is pointing to 
<BREWisdkiexamples>. 


2. Choose the MediaPlayer application. 


BREW loads the MediaPlayer applet DLL and starts the application. A splash 
screen opens, and a screen similar to the following appears: 


Tl «oa 


MediaFlaver 


| + Play File... 
Record MCP File... 





3. From the MediaPlayer Main Menu, you can perform the following functions: 


Select this option To do this 


Play File Select an audio, video, or still graphic file to run on the handset. 
See Viewing or playing a multimedia file below for instructions. 


Record QCP File Record a QCP audio file using a microphone to emulate the 
device mouthpiece. See Recording a QCP audio file on page 21 
for instructions. The recorded file can be played using the Play 
File menu option. 


About View copyright information for MediaPlayer. 


4. Tostop the applet at any time, press End. 


Viewing or playing a multimedia file 
The Play File menu option lets you select the audio, video, or still graphic file to be run on the 
handset screen. Each of these types of media are described below. 
To play an audio file 
1. Choose Play File from the MediaPlayer Main Menu. 
The Select File screen opens. 
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Tull € DNE) 
MediaFlover 

Select File 

1) canvon.mid 


- Egyvpad.bmp 
1) masound acp 
1] piano. mp3 





2. Highlight the audio file (MIDI, QCP, or MP3) you want to play and press Select. 


A screen similar to the following opens. 


Tl «oa 


MediaFlaover 
canpon. mid 





3. To play the audio clip, press Select. 


The sound clip plays and the status bar at the bottom displays the time elapsea. 


Tl «oa 


MediaFlover 
Canyon. mid 


PL OO DADA 





The other controls are described below. 


Ip 44 0] bh da TP 


» Ss 8 MO MK 
% A 
% S, ZA 
o 8 


Y 
% 


4. When you are finished playing the media file, press CLR. 
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The Select File screen reopens. 


To play a video file 


1. From the Select File screen, highlight the video file (BC|) you want to play and 
press Select. 


The video plays. 


Tl LU 


MediaFlaver 
dog.bci 





2. To clear the screen and show only the video, press the Select key to select the 
Zoom (magnifying glass) toolbar button. 


NOTE: The Zoom button is available only for BCI and BMP files. 


The video plays without displaying the information at the top of the screen or the 
button bar. 





3. Press any key to return to the previous view. 
4. When you are finished playing the media file, press CLR. 


The Select File screen reopens. 
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To view a still image 


1. 





From the Select File screen, highlight the image file (BMP) you want to view and 
press Select. 


A screen similar to the following appears. 


Tl «oa 


MediaFlover 
Eeypad.bmp 


- To clear the screen and show only the graphic, press the Select key to select the 


Zoom toolbar button. 


The image appears without displaying the information at the top of the screen or 
the button bar. 





Press any key to return to the previous view. 

You can also use the arrow keys to scroll the graphic left, right, up, and down. 
When you are finished viewing the still graphic image, press CLR. 

The Select File screen reopens. 


To exit MediaPlayer, press End. 
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Recording a QCP audio file 


MediaPlayer allows you to record your voice or any other sound through the device 
mouthpiece and then, using the Play File menu option, replay the recorded sounds. There is 
no limit to the length of each recording; however, due to the limited amount of memory 
available on a handset, the durations should be relatively short. 


To record a QCP file 


1. 


3. 





Choose Record QCP File from the MediaPlayer Main Menu. 


The Record screen opens. 


Tl «nua 


MediaFlaver 
sample. grp Filename for your recording 


Record button 


Notice that there is a filename at the top of the screen. This is the filename to be 
used for the recording. Also notice that the button bar now includes the green 
Record button. 


Highlight the Record button and press Select. 
The Record screen shows the elapsed time of the recording above the button bar. 


When you want the recording to stop, highlight the Stop button and press Select 
again. 


The recording is saved with the name that appears at the top of the screen. This 
file is now available for selection when you choose the Play File option from the 
MediaPlayer Main Menu. 
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What MediaPlayer demonstrates 


MediaPlayer demonstrates how to create a BREW multimedia application. The BREW 
programmer used IMedia and IMedia-based interfaces to build a media player that plays and 
records all multimedia formats, including audio and video. Currently, only QCP recording is 
supported, and it requires that you have the appropriate CMX DLLs loaded. MediaPlayer uses 
IImageCtl and Ilmage interfaces to display images. The programmer offers the following basic 
guidelines to help you create similar types of applications. 


* Create your own interface (abstract base class) and use it in the application. 
MediaPlayer has an IWindow interface that is inherited by all the windows. Each 
window is capable of redrawing itself and handling the evenis sent to it. There are 
three windows: 


— The Main window manages the main menu. 
— The FileList window allows the user to select from the list of media files. 
— The Player window enables playback and recording controls. 


* Use various controls, such as IMenuCil, IImageCil, and IStatic. MediaPlayer also 
shows how you can use IDisplay to implement your own progress bar control. 


* Enable cooperative multitasking through the ISHELL Resume() API, which is used 
to break a big task into smaller chunks. In MediaPlayer, the IWindow redraw occurs 
asynchronously. MediaPlayer also demonstrates usage of asynchronous timers in 
the application. 


* Use user-defined events in your application. For example, MediaPlayer uses user- 
defined events to create IMedia-based classes. 
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NeiDiagnostics is an application that allows the device user to perform echo tesis using the 


TCP/IP and UDP/IP protocols to a user-specified host or IP address, and HTTP tests that can 
retumn a specified URL, as well as information such as transmission speed. 


NetDiagnostics specifications 


The following table lists the interfaces and controls used in the development of 
NetDiagnostics, along with the files you need to run the application on the handset. 


Interfaces used Controls used Files needed on handset 
INetMgr IHtmlViewer netdiagnostics.bar 
Socket netdiagnostics.mif 
netdiagnostics.mod 
IRimiViewer netdiagnostics.sig 
IWeb nd about.him 
IWebOpts nd echotests.him 
nd help.him 
hiiadaa nd helpecho.htm 
ISource nd helphttp.htm 
|SourceUtil nd httptests.him 
nd mainmenu.htm 
IPeek 
IGetLine 


Running NetDiagnostics on the handset 


Before exploring the underlying code that makes NetDiagnostics work, take a look at the 
application from the user's perspective; that is, how it works on a handset. 
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To run NetDiagnostics 


1. Run the BREW Simulator and make sure the MIF Directory setting is pointing to 
<BREWisdkiexamples>. 


2. Choose the NeiDiagnostics application. 
BREW loads the NetDiagnostics applet DLL and starts the application. A splash 


screen opens, and a screen similar to the following appears: 


Tl «nua 


Methiacgnostics 


Echo Tests 





3. From the NetDiagnostics Main Menu, you can perform the following functions: 


Select this option To do this 


Echo Tests Perform echo tests on the device using the TCP/IP or UDP/P 
protocol. See Performing echo tests below. 


HTTP Tesis Test connection response information for a user-specified 
URL. See Performing HTTP tests on page 26 for instructions. 


Help View online instructions for using NetDiagnostics. 


About View copyright and version information for NetDiagnostics. 


4. To stop the applet at any time, press CLR. 


Performing echo tests 


The Echo Tests menu option lets you specify a series of parameters for testing, such as a 
destination host or IP address, a text message to be transmitted, and the type of networking 
protocol to be tested. When the tesis are run and network access is tested, you have the option 
Of viewing response information, as well as response time information. 


To run the echo tests 


1. Choose Echo Tests from the NeiDiagnostics Main Menu. 
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The Echo Tesis screen opens. 


«nua 


Network, Áccess 


E Show Fesponse 
e Soy Hmings 
o TCP 





2. To change the destination host or IP address, highlight Host and press Select. 


The address becomes an editable field. You can perform the following text editing 
functions: 


To perform this edit Do this 


Enter text characters Press the right and left arrow keys and the text 
characters on the device keypad. 


Enter numbers Perform these steps: 


* Press Select to highlight Done. 


* Press the right arrow to highlight 
Multitap. 


* Press Select. 
* Highlight Numbers and press Select. 


* Now press the device keypad to type 
numbers. 


Enter symbols Perform these steps: 


* Press Select to highlight Done. 

* Press the right arrow to highlight 
Multitap. 

* Press Select. 

* Highlight Symbols and press Select. 
The screen shows a series of symbols 
with their associated keys on the device 
keypaad. 

* To see more symbol choices, press the 
down arrow key. 

* Press the device keypad to enter the 
associated symbol. 


3. To change the message to be transmitted, highlight Message and press Select. 
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The message becomes an editable field and the same editing functions as Host are 
available. 


-. The Show Response check box indicates whether you want to view the response 


from the host. You can change the selection by highlighting the check box and 
pressing Select. 


- The Show timings check box indicates whether you want to view response time 


information, such as the total transmission time (in milliseconds), send time (in 
milliseconds at a specified number of bits per second), and receive time (for 
example 10 ms O 2000 bps). You can change the selection by highlighting the 
check box and pressing Select. 


- Select either the TCP or UDP Internet Protocol. This is a radio bution-type setting. 


You must select one option or the other; selecting both is not possible. To change 
the selection, highlight the protocol you want to use for the tests and press Select. 


NOTE: To view onscreen definitions of the fields, highlight Info and press Select. 
When you are finished, press CLR. 


-. When you are finished selecting testing parameters, press Start. 


The tests are run and a screen similar to the following appears. 


Tal. dE 
É startino... 

E connechno... 

E yrtino complete... 

E readina... 

“* reading Complete... 


etmork. dccess Tesl 
otal Time: E41 mz 
Send Time: Uma dl 





- To clear the test screen, press CLR. 


The NetDiagnostics Main Menu reopens. 


Performing HTTP tests 


The HTTP Tests menu option lets you specify a series of parameters for testing the HTTP 
connection to a specified URL. When the tesis are run, you have the option of viewing 
response information, as well as response time information. 
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To run the HTTP tests 


1. 








Choose HTTP Tests from the NeiDiagnostics Main Menu. 


The HTTP Tests screen opens. 


Tull OO] 
HTTE Tests 


URL: 


DO Shom Response 


EM Show timing: 


To change the target URL destination, highlight URL and press Select. 


The URL becomes an editable field. You can perform the same text editing 
functions described in the previous procedure. 


The Show Response check box indicates whether you want to view the HTTP 
connection response from the target URL. You can change the selection by 
highlighting the check box and pressing Select. 


The Show timings check box indicates whether you want to view response time 
information. You can change the selection by highlighting the check box and 
pressing Select. 


NOTE: To view onscreen definitions of the fields, highlight Info and press Select. 
When you are finished, press CLR. 


When you are finished selecting testing parameters, press Start. 


The testis are run and a screen similar to the following appears. 


connectina... 
+ di 

sending... 

recelvina... 


ontent=typectext "html 
onnectionclose 


got response... 


* into code: 200 
To clear the test screen, press CLR. 
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The NetDiagnostics Main Menu reopens. 


What NetDiagnostics demonstrates 


NetDiagnostics demonstrates how to create a BREW application that utilizes the various 
BREW network interfaces. The GUlis driven by the IHitmlViewer interface, which allows HTML 
documents to be viewed on the phone screen. Each application screen is generated by 
accessing an HTML file stored in the phone's file system, and displaying it in the IHimlViewer 
object. The user navigates the interface by selecting the various links displayed in the HTML 


page. 


The application performs two types of network connectivity tests: 


These tests Allow the user to do this 


Echo Tests Send TCP or UDP messages to a specified echo server. The user specifies the host, 
message text, transmission type (TCP or UDP), and the response parameters in an 
onscreen HTML form. After the test is initiated, the application displays the status of 
the transmission, returned message, and transmission statistics. 


HTTP Tesis Access an Internet address using the HTTP protocol. The user specifies the URL and 
display parameters in an onscreen HTML form. After the test is initiated, the 
application displays the status of the transmission, returned HTML source code, and 
transmission statistics. 


Network connectivity is handled using the INetMgr, ISocket, IWeb, IWebOpis, and IWebResp 
BREW APl interfaces. HTML text is parsed and displayed by the IHimlViewer, ISource, 
ISourceUtil, IPeek, and IGetLine Interfaces. 
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Road Warrior is an application that connecis to the California Depariment of Transportation 
web server and delivers real-time traffic data for major San Diego highways. The web server 
URL and highways are configurable. 


Road Warrior specifications 


The following table lists the interfaces and controls used in the development of Road Warrior, 
along with the files you need to run the application on the handset. 


Interfaces used Controls used Files needed on handset 

IApplet IMenuCil roadwarrior.bar 

Display Static roadwarrior.dat 

File roadwarrior.mif 
roadwarrior.mod 

IFileMgr roadwarrior.sig 

Image 

INetMgr 

IShell 

ISocket 

ISource 

IWeb 

IWebResp 


Running Road Warrior on the handset 


Before exploring the underlying code that makes Road Warrior work, take a look at the 
application from the user's perspective; that is, how it works on a handset. 
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To run Road Warrior 


1. 





Run the BREW Simulator and make sure the MIF Directory setting is pointing to 
<BREWisdkiexamples>. 


Choose the Road Warrior application. 


BREW loads the Road Warrior applet DLL and starts the application. A splash 
screen opens, and a screen similar to the following appears: 


Road Warrior 


Help 


about 

|-5 Morth 
|-5 South 
|-G East 





Highlight the highway and direction for which you want to acquire speed 
information, and press Select. 


The application connecis to the web server, and the following screen opens. 


Road Warrior 


5 NORTH-Det-21: || <q Highway, direction, date, and time 
DO BE Hawthorm St 
O El lhdia St Highway speed and intersection 


O AO San Diego vel 
D GO Ola Tom dele 


The scrolling banner along the top shows the selected highway and direction, and 
the date and time the data was taken from the freeway. The number to the left of 
each intersection is the current speed of traffic. As you scroll down through the 
intersections, the graphic display at the bottom of the screen whimsically 
approximates the amount of traffic at each intersection, as shown here. 
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Road Warrior 


OD E” Camino del Nort 
OD 64 Egrmardo Cente 


OD E4 Rancho Berna 


ED & Pomerado Rowe 
D 52 %ja Pancho Par Flow of traffic at selected intersection 





4. Tostop the applet at any time, press End. 


What Road Warrior demonstrates 


Road Warrior is an application that provides the user with real-time traffic speeds. It presenis 
data for San Diego County freeways only, but it can be used as a model for similar applications 
in other geographical areas. 


Road Warrior demonstrates how to use the IWeb interface to get information from a publicly 
available web server, and then parse the resulting HTML to prepare the data for display to the 
user. It also demonstrates the following: 


lt shows how to provide feedback to the user of a potentially time-consuming 
network operation that is currently in progress, and how to allow the user to cancel 
out of the network connection. 


lt uses static and animated images to help beautify an otherwise all text-based 
application. 


lt shows how suspend and resume of a BREW application should be handled, 
including management of the active states of controls, and the stopping and starting 
of animations. 


lt uses the IMenuCil interface to display information and get user input, including 
custom key press handling. 


It provides an example of how to persistenily save user preferences across different 
running sessions of the application. 


lt demonstrates how to perform simple file reading, including a mechanism to read 
large blocks of text in at one time to improve file system performance. 
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lt queries the BREW device at runtime to determine screen color depth, and 
configures menu control styles based on that information. 


lt provides an example of how to put strings in string resources so that the application 
can be easily translated into other languages. 


lt shows techniques for minimizing the number of keystrokes the user has to press: 
type-to-select and remembering last used items. 


Most importantly, Road Warrior demonstrates a real-life application that has passed 
TRUE BREW Testing and is being used in commercial BREW environments. 
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AN 


This “virtual whiteboard” application allows the user to draw geometric shapes of various sizes 
and colors. All or part of a drawing can be erased at any time. The size of shapes is limited by 
the device screen size, and the choice of colors is limited by the color depth supported by the 
device. 


WhiteBoard specifications 


The following table lists the interfaces and controls used in the development of WhiteBoard, 
along with the files you need to run the application on the handset. 


Interfaces used Controls used Files needed on handset 
IBitmap IMenuCil whiteboard.bar 
IDisplay IStatic whiteboard.mii 
, whiteboard.mod 
SSpRICS whiteboard.sig 
Image help.txt 


Running WhiteBoard on the handset 


Before exploring the underlying code that makes WhiteBoard work, take a look at the 
application from the user's perspective; that is, how it works on a handset. 


To run WhiteBoard 


1. Run the BREW Simulator and make sure the MIF Directory setting is pointing to 
<BREWisdkiexamples>. 


2. Choose the WhiteBoard application. 


BREW loads the WhiteBoard applet DLL and starts the application. A splash 
screen opens, and a screen similar to the following appears: 
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3. From the WhiteBoard Main Menu, you can perform the following functions: 


Select this option To do this 


Draw Draw on the whiteboard using the shapes and colors selected 
using the Option menu option. See Drawing on the whiteboard 
on page 37 for instructions. 


Tools Specify the shape and color for drawing and the fill color. See 
Setting draw options on page 34 for instructions. 


Help View online instructions for using WhiteBoard. 


About View copyright and version information for WhiteBoard. 
4. Tostop the applet at any time, press End. 


Setting draw options 


The Tools menu option lets you select the shape that you want to draw, and the border and fill 
colors. The following shapes are available. Instructions for drawing each shape follow. 


Shape Example 
Line 
Polyline 
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Shape Example 
Arc 
Circle Draw Mode 
Ellipse TER 

o 
Pie 
Rectangle 
Triangle 

an 

Polygon 


NOTE: In addition to the shapes shown above, those shapes that are enclosed, such as 
circles, rectangles, and polygons, can be filled with black or any other color. Lines and the 
borders of shapes can also be assigned a color. 


To select a shape 


1. Choose Tools from the WhiteBoard Main Menu. 
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The Tools Menu screen opens. 





Shapes 


- With Shapes highlighted, press Select. 


The Shapes Menu screen opens. 





- Select the type of shape you want to draw. The following table describes the 


shapes available under the three menu options on the Shapes menu. 


Select this menu option To draw these shapes 


Lines Line 
Polyline 
Arc 


Filled Shapes Circle 
Ellipse 
Rectangle 
Triangle 
Polygon 


Unfilled Shapes Circle 
Ellipse 
Pie 
Rectangle 
Triangle 
Polygon 
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4. When you have made your shape selection, do one of the following: 


* lfyou want to change the border color, or if you selected an enclosed shape, 
such as a circle, and want to change the fill color, see To select a border or fill 
color below. 


* lIfyou do not want to change the color, press CLR. 


The WhiteBoard Main Menu opens. 


To select a border or fill color 
1. From the Tools menu, choose Color. 


The Select Colors screen opens. 





The selected shape appears in the screen; in this case, an unfilled Rectangle 
shape was selected. If a filled shape had been selected, the screen would also 
show the Mode field which allows you to switch between Border color and Fill color. 


2. To change the border color, select Border in the Mode field and specify the RGB 
values for the color you want to use. 


3. To change the fill color, select Fill in the Mode field and specify the RGB values for 
the color you want to use. 


4. When you are finished selecting colors for the shape, press Done. 


The WhiteBoard Main Menu screen opens. 


Drawing on the whiteboard 


After you have used the Tools to select a shape and, optionally, colors, you are ready to use 
the Draw menu option to draw geometric shapes on the whiteboard. You can change the 
drawing shape at any time and shapes can overlap. 
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To draw on the whiteboard 


1. Choose Draw from the WhiteBoard Main Menu. 


The WhiteBoard screen goes into Draw Mode. 


wWhiteBoard 


DDR NS fo 





2. Using the arrow keys, move the crosshairs to draw the selected shape. Each shape 
requires a different drawing method, as described in the procedures that follow. 


NOTE: When you are in Draw Mode, the crosshairs move 1 pixel each time you 
press one of the arrow keys. To increase the distance of each movement, press 
one of the number keys. For example, to have the crosshairs move 7 pixels each 
time you press an arrow key, press the 7 key. 


3. When you are finished drawing, press CLR. 


The WhiteBoard Main Menu opens. 


NOTE: The CLR key can also be used to delete a drawing before you have 
committed it to the white board. For more information, see Undo on page 41. 

To draw a line 

1. Move the crosshairs to the point where you want the line to start and press Select. 
A small flashing dot appears. 

2. Move the crosshairs to the point where you want the line to end and press Select. 


A line connecis the two points. 


To draw a polyline 


1. Move the crosshairs to the point where you want the polyline to start and press 
Select. 


A small flashing dot appears. 
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Move the crosshairs to the point where you want the first line to end and press 
Select. 


Another dot appears. 
Repeat step 2 until you have reached the point where you want the polyline to end. 
Press Select a second time at the last point. 


A polyline connecits the dots. 


To draw an arc 


dl 


Move the crosshairs to the point where you wantthe center of the arc to appear and 
press Select. 


A small flashing dot appears. 


Move the crosshairs to the point where you want the radius and starting angle of 
the arc to appear and press Select. 


Another dot appears. 


Move the crosshairs to the point where you want the ending angle of the arc to 
appear and press Select. 


Press Select again. 


An arc connects the dots. 


NOTE: WhiteBoard draws arcs in a counterclockwise direction. Therefore, if you 
specify a location for the starting angle of the arc that is lower on the Y axis than 
the ending angjle, the resulting arc will be less than 180 degrees. If the location for 
the starting angle of the arc that is higher on the Y axis than the ending angjle, the 
resulting arc will be more than 180 degrees. 


To draw a circle 


LÊ 


Move the crosshairs to the point where you want the center of the circle to appear 
and press Select. 


A small flashing dot appears. 


Move the crosshairs to the point you want to use for determining the radius of the 
circles along the X axis and press Select. 


A circle is drawn. 
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To draw an ellipse 


1. 


Move the crosshairs to the point where you want the center of the ellipse to appear 
and press Select. 


A small flashing dot appears. 


Move the crosshairs to the point you want to use for determining the semi-X and 
semi-Y axis of the ellipse and press Select. 


An ellipse is drawn. 


To draw a pie 


1. 


Move the crosshairs to the point where you want the center of the pie to appear and 
press Select. 


A small flashing dot appears. 


Move the crosshairs to the point where you want the radius and starting angle of 
the pie to appear and press Select. 


Another dot appears. 


Move the crosshairs to the point where you want the ending angle of the pie to 
appear and press Select. 


Press Select again. 


A pie connecis the dois. 


NOTE: Like arcs, WhiteBoard draws pies in a counter-clockwise direction. 
Therefore, if you specify a location for the starting angle of the pie that is lower on 
the Y axis than the ending angle, the resulting pie will be less than 180 degrees. If 
the location for the starting angle of the pie that is higher on the Y axis than the 
ending angle, the resulting pie will be more than 180 degrees. 


To draw a rectangle 


e 


Move the crosshairs to the point where you want one corner of the rectangle to 
appear and press Select. 


A small flashing dot appears. 


Move the crosshairs to the point where you want the opposite corner to appear and 
press Select. 


A rectangle is drawn. 
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To draw a triangle 


1. Move the crosshairs to the point where you want one angle of the triangle to appear 
and press Select. 


A small flashing dot appears. 


2. Move the crosshairs to the point where you want the second angle to appear and 
press Select. 


Another dot appears. 


3. Move the crosshairs to the point where you want the third angle to appear and 
press Select. 


A triangle connecis the three poinis. 


To draw a polygon 


1. Move the crosshairs to the point where you want one angle of the polygon to 
appear and press Select. 


A small flashing dot appears. 


2. Repeai step 1 until you have reached the point of the last angle and press Select 
again. 


A polygon connecis the points. 
Some final notes about drawing 


In addition to drawing, WhiteBoard offers a few features that enhance the usefulness of the 
application, including an Undo feature, a Scrolling feature that allows the user to extend the 
drawing horizontally beyond the width of the device screen, and a Clipping feature. 


Undo 


When you draw a given shape, a triangle for example, the positions for the angles are saved 
in the device's memory until the final shape is drawn. If you press CLR before the shape is 
completed (that is, before you set the third point), all points for the shape are deleted. 
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Scrolling 


When you are in Draw Mode, you can extend your drawing beyond the confines of the device's 
screen width. The scroll bar at the bottom of the screen allows you to scroll twice the width of 
the device screen. 


Clipping 


The Clip feature allows you to delete a rectangular portion of your drawing. To clip a drawing, 
finish drawing the current shape and then press Select twice at one corner of the clipping 
rectangle. Move the crosshairs to the opposite corner of the rectangle and press Select again. 
All drawing within the selected rectangle is deleted. You can delete a small portion of the 
screen or the entire screen using this feature. 


What WhiteBoard demonstrates 


WhiteBoard demonstrates how to create a BREW application that utilizes the graphics 
capabilities of the BREW API. The sample application allows the user to render simple 
geometric shapes to the phone's display in a scrolling, rectangular, drawing canvas. The user 
can select shapes, and set the border and fill color of each. A cursor is used to plot points on 
the drawing canvas to draw the selected geometric shape. 


The application allows users to select filled and unfilled drawing shapes by navigating through 
a series of Icon List menus. A form is also available to allow the user to set and view the color 
settings for a particular shape. After the shape and color settings have been selected, the user 
can draw the shape on the canvas by plotting points which represent the required vertices of 
the shape to be drawn. 


Extensive use is made of the BREW IGraphics interface for drawing lines, polylines, arcs, 
circles, ellipses, rectangles, triangles, pie, and polygons of various dimensions. The canvas is 
implemented using two graphics buffers, the screen display and a separate ofíscreen IBitmap 
buffer. The screen display graphics buffer is used to display the drawing cursor and plotted 
poinis. Shapes are rendered to the IBitmap buffer and updated to the phone screen buffer 
when needed. Using the AEE RO XOR raster operation, the cursor image and poinis drawn 
on the phone screen with the underlying image, cursor, and point movement is made to appear 
transparent on the screen. 


The IBitmap ofíscreen buffer is wider than the phone screen to allow the canvas to be scrolled 
in the horizontal direction. 
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Adding expenses in ExpenseTracker 8 
Arcs, drawing with WhiteBoard 39 


C 


Circles, drawing with WhiteBoard 39 
Clipping in WhiteBoard 42 


D 


Drawing with WhiteBoard 38 


E 


Echo tests in NetDiagnostics 24 
Editing expense records in ExpenseTracker 11 
Ellipses, drawing with WhiteBoard 40 
Expense reporis, loading in ExpenseTracker 12 
ExpenseTracker 

adding expenses 8 

editing expense records 11 

loading and saving expense reports 12 

overview / 

running on the handset 7 

viewing expenses 9 

what it demonsitrates 14 


- 


Features, requesting new 6 
Fill colors, selecting with WhiteBoard 37 


H 


HTTP tests in NetDiagnostics 26 


Interfaces and controls used 
Expense Tracker 7 
MediaPlayer 16 
NetDiagnostics 23 
Road Warrior 29 
WhiteBoard 33 


Index 


L 


Lines, drawing with WhiteBoard 38 


M 


MediaPlayer 
overview 16 
playing a video file 19 
playing an audio file 17 
recording a QCP audio file 21 
running on the handset 17 
scrolling in an image 20 
viewing a still image 20 
what it demonsitrates 22 


N 


NetDiagnostics 
overview 23 
running echo tesis 24 
running HTTP tests 26 
running on the handset 24 
what it demonsitrates 28 
Numbers, entering with NetDiagnostics 25 


P 


Pies, drawing with WhiteBoard 40 
Playing 
audio file with MediaPlayer 17 
video with MediaPlayer 19 
Polygons, drawing with WhiteBoard 41 
Polylines, drawing with WhiteBoard 38 


Q 


QCP files, recording 21 


R 


Recording audio with MediaPlayer 21 
Rectangles, drawing with WhiteBoard 40 
Requesting new BREW features 6 
Road Warrior 

overview 29 

running on the handset 30 
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Scrolling images with MediaPlayer 20 
Scrolling in WhiteBoard 42 
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Shapes, selecting with WhiteBoard 35 
Symbols, entering with NetDiagnostics 25 


T 


TCP 26 

Text characters, entering with NetDiagnostics 25 
Triangles, drawing with WhiteBoard 41 

TRUE BREW Testing 5 


U 


UDP 26 
Undo in WhiteBoard 41 
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Web site, BREW 6 
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drawing 38 
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